Templates
Documents to copy and fill in. Both are deliberately structured so that the sections nobody wants to write — security, governance, exit — cannot be quietly omitted.
- Reference architecture — the full document structure for describing an architecture, from problem statement to implementation roadmap
- Architecture decision record — one decision, one page
Which to use
| Situation | Document |
|---|---|
| Describing an architecture for a class of systems (a national exchange, a platform) | Reference architecture |
| Describing one system in one context | Solution architecture — same template, with technologies named |
| Recording a single decision | ADR |
| Reviewing a proposal | Checklists |
The distinction between reference and solution architecture matters and is covered in architecture overview.
How to use them
Fill in every section, including the ones you would rather skip. If a section genuinely does not apply, write "not applicable" and why. An empty section is ambiguous; an explicit dismissal is a decision.
Keep them short. A reference architecture nobody reads has failed. Aim for the shortest document that answers the questions.
Put them in version control, next to the code or in an architecture repository, so changes are reviewable and dated.
Date everything. An undated architecture document is folklore.